Skip to content

Contract: a request has no deadline; expiresAt and lifetimeMs are deprecated and ignored - #92

Open
dmurphy5 wants to merge 2 commits into
masterfrom
dylan/contract-no-deadlines
Open

dmurphy5 wants to merge 2 commits into
masterfrom
dylan/contract-no-deadlines

Conversation

@dmurphy5

Copy link
Copy Markdown

Why

The top goal of the library is that every request started on the device reaches the server. A deadline works against that goal: it is a cancel() that the library runs on a timer. The only app that uses the library sets a 10-year lifetime and queues again what expires. So the library drops deadlines. An app that needs a bound calls cancel(id) itself.

This PR is the JS side: the contract, the fake native module, the tests and the docs. Two other PRs remove expiry from Android and iOS. This PR must ship in the same release as those two.

What changes

  • expiresAt and lifetimeMs are deprecated and ignored. Both stay in the types for this release, so app code written for 11.3.0 compiles and runs with no change. They leave the types in the next major release.
  • No refusal for these fields. mutate() used to reject an expiresAt that was not finite, zero or negative, and configure() did the same for lifetimeMs. Now both accept any value. An ignored value must never be the reason a request is refused.
  • A warning in development. The first mutate() whose descriptor sets expiresAt, and the first configure() that sets lifetimeMs, warn one time per client. The warning goes to onWarning, or to console.warn when no sink is set. Production builds do not warn.
  • What crosses to native.
    • configure() no longer sends lifetimeMs. Native on master never read it.
    • Every enqueue sends expiresAt: 8640000000000000, the largest valid Date, whatever the definition set. Native on master requires a number there: Android rejects with "descriptor.expiresAt is required" (EntryParsing.kt), and iOS with "missing 'expiresAt'" (EnqueueParser.swift). So every new or re-queued request cannot expire, with this PR alone or with the native PRs.
  • Entries an earlier version queued. A live entry that is never queued again keeps its stored deadline until the native side stops reading it, in the same release. After that it keeps going. An entry that already settled expired stays an error row until cancel() or a same-id mutate().
  • errorKind: 'expired' is deprecated. New and re-queued requests never settle expired. An expired outcome that JS did not acknowledge still reaches onError after the upgrade, as before.
  • Fake native module. It never had an expiry model, and it still has none. Its docs now say so, and show how a test seeds an old expired outcome with buildSettled(id, outcome, { deliveries: 0 }) and seedUnacknowledged().
  • Docs. The README has a "No deadlines" part at the top of "Reliable delivery". Every sentence that described expiry is gone or corrected. The codegen spec comments, the type docs and the CHANGELOG (## Unreleased) match. The example app keeps its "Expires in s" field to check that nothing expires; its Android step 9 and iOS step 13 now test that.

Behavior change

  • A descriptor expiresAt or a configure() lifetimeMs does nothing. Before, they set when a request settled error with errorKind: 'expired'.
  • Until the native PRs land, a live entry that an earlier version queued can still expire on its stored deadline. This is why the three PRs must ship together.
  • A bad value for either field no longer throws.
  • configure() sends one less key to native.
  • In development, an app that sets either field sees one warning per client.
  • An app's tests that check the expiresAt value sent to native now see the fixed value, and tests that run in development mode see the warning.

What it does not change

  • No Android or iOS code changes in this PR.
  • The public types keep expiresAt, lifetimeMs and 'expired', so no app code has to change.
  • Delivery, acks, retries and the same-id rules do not change. No JS comparison used expiresAt. It stays in the list of known descriptor fields, so a descriptor that sets it is accepted.
  • test-vectors/ does not change.

Tests

  • Jest. The tests changed first and failed on master: 25 failures. They cover:

    • expiresAt accepted with any value, and the fixed value sent.
    • The same entry sent for a same-id mutate() whatever expiresAt it sets.
    • lifetimeMs accepted with any value and not forwarded.
    • One warning per client, and none outside development.

    These tests pass on master too, by design: an old expired outcome reaching onError (in delivery and through the fake), and the fake never expiring an entry.

  • Type tests (src/__typetests__/deadlines.ts). A descriptor with expiresAt and configure() with lifetimeMs compile. ErrorKind still has 'expired', and an exhaustive switch over it compiles.

  • Mutation checks. Each break below was made on purpose, and at least one check failed for each:

    • Remove expiresAt, lifetimeMs or 'expired' from the types (typecheck fails).
    • Drop expired outcomes in delivery.
    • Stop sending expiresAt. Send a 14-day deadline. Forward lifetimeMs to native again.
    • Throw again on a bad expiresAt or lifetimeMs.
    • Warn every time. Warn outside development. Do not warn.
    • Send the app's expiresAt when set. Drop expiresAt from the known descriptor fields.
    • Make the fake expire an entry. Make the fake drop a seeded expired outcome.
  • Local checks. yarn test passes (exit 0, 322 tests in 7 suites). yarn typecheck passes (exit 0). yarn lint:ci passes (exit 0).

Review

An independent review agent checked the fixed value against the native code on this branch (iOS by test, Android by reading) and found no code defect. On both platforms a different expiresAt in a same-id mutate() only replaces the stored deadline; it never restarts an upload.

🤖 Generated with Claude Code

dmurphy5 and others added 2 commits November 18, 2026 16:14
The library never expires a request. expiresAt on a descriptor and
lifetimeMs in configure() stay in the types, deprecated and ignored:
mutate() and configure() accept any value and warn once per client in
development. configure() no longer sends lifetimeMs. Every enqueue sends
expiresAt 8640000000000000, because native in 11.3.0 rejects an entry
without one. errorKind 'expired' is deprecated; an outcome an earlier
version journaled still reaches onError.

README, CHANGELOG, the codegen spec comments, the fake native docs and the
example app's expiry steps now describe no deadlines.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
JS sends every new or re-queued request with a fixed far-future deadline,
so it cannot expire. A live entry that an earlier version queued keeps its
stored deadline until the native side stops reading it, in the same
release. An entry that already settled expired stays an error row. The
README's seeding example now passes deliveries: 0, so the first delivery
counts 1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant